Add Block Device Support #191

will-v-pi · 2024-12-18T17:50:33Z

Adds support for using ls, mkdir, cp (including between host and device), rm, and cat commands, with LittleFS (used by MicroPython) or FatFS filesystem support.

Works with block devices specified in the binary info, and with partitions. It autodetects the file system if --filesystem is not specified, and also supports formatting the block device if required with the -f argument.

This fixes #58

Add ls, mkdir, put and get commands to access block devices Currently only supports littlefs

…lity to specify directory

Default to writeable and formattable, but override based on bdev flags, or partition NSBOOT permissions

Adds ls and cp commands for FatFS

…ranslation Layer (prevents doing lots of erases) Change Fat sector size back to 512, and consequently add in flash translation error - wasn't needed before with 4096 sector size Also enable LFN support

Need to put BLOCK_DEVICE_PARTITION_ID into the SDK somewhere

README.md

lurch · 2025-08-25T07:19:52Z

README.md

+            Specify filesystem to use
+        <fs>
+            littlefs|fatfs
+        -f, --format


Hmmm, we now seem to have BOTH -f, --format and -f, --force flags?! Either this worn't work properly, or if it does work it's pretty confusing!

Good spot - I’ll make this filesystem one not have a short argument

(perhaps the arg-parsing library could/should raise an error if given the same argument multiple times?)

(perhaps the arg-parsing library could/should raise an error if given the same argument multiple times?)

I will leave that for a future PR

README.md

lurch · 2025-08-25T07:29:02Z

README.md

+
+### cp
+
+Copy file to/from the block device - use :filename to indicate files on the device (eg `cp main.py :main.py` to upload to the device)


Does this bdev cp command check that one (and only one) of either src or dest starts with a colon?

Does it only work for files and not directories?

If the answer to the previous question is "only files", would it be a lot of additional work to be able to copy directories? (which would presumably need to operate recursively)

No - you can copy a file to somewhere else on the device, or even use this to copy local files if you really wanted

Yes, it only works for files

Could probably add that - just needs a recursive walk like ls has

lib/littlefs/README.md

lurch · 2025-08-25T07:50:43Z

main.cpp

+
+    group get_cli() override {
+        return (
+            optional_untyped_file_selection_x("dirname", 0) +


Does the optional_ here indicate that this is an optional argument? If so, it should probably appear in the README.md as [dirname] rather than <dirname> ?

Yes, it’s optional - I’m not sure why the CLI stuff isn’t putting square brackets around it

main.cpp

README.md

lurch · 2025-08-25T09:13:22Z

A thought I just had - to make this slightly easier to use, could you have picotool check what filename it was invoked with (e.g. like busybox does), and then you could have picotool_ls, picotool_cat, etc. symlinks to the picotool binary, and then calling picotool_ls somedir would do the same thing as picotool bdev ls somedir ? (Or if that's not possible, perhaps the picotool CMake install could add a bunch of shell scripts e.g. named picotool_ls which just does picotool bdev ls $@)

will-v-pi · 2025-08-25T14:31:25Z

A thought I just had - to make this slightly easier to use, could you have picotool check what filename it was invoked with (e.g. like busybox does), and then you could have picotool_ls, picotool_cat, etc. symlinks to the picotool binary, and then calling picotool_ls somedir would do the same thing as picotool bdev ls somedir ? (Or if that's not possible, perhaps the picotool CMake install could add a bunch of shell scripts e.g. named picotool_ls which just does picotool bdev ls $@)

I think that might be best left to the user to do, to avoid polluting their shell (eg you might want picotool_ls to list devices, not use the bdev command) - you could also create an alias to picotool bdev in bashrc (which also avoids the need for underscores and therefore the shift key), so I don’t think I’ll include that is this PR

Add extra checks to prevent too big files Fix dirname description Remove short format option Improve erase check (rather than just checking for FF)

main.cpp

README.md

lurch · 2025-09-01T09:46:12Z

README.md

+        --format
+            Format the drive if necessary (may result in data loss)


Presumably using the --format option in conjunction with picotool bdev ls will always return an empty directory listing? 😂 But this makes me wonder why --format is an option that can be used in combination with any other picotool bdev command, rather than just being a standalone picotool bdev format or picotool format_bdev command? 🤔

I added it as a flag because of where the formatting occurs in the code - it will only format the drive if no filesystem (of the type specified by --filesystem if that is passed) is detected, so you could always call your first command with --format if you wanted to make sure you always do the command. Eg this works for both formatting new devices and updating the file on old devices:

picotool bdev cp main.py :/ --format --filesystem littlefs

Oh! I see now that I'd misread "Format the drive if necessary" as just "Format the drive" 🤦

So I guess that means if you had a blockdevice that was already fatfs-formatted, and you wanted to explicitly reformat it, you'd need to do something like:

picotool bdev ls --format --filesystem littlefs picotool bdev ls --format --filesystem fatfs

?

Yes, so it probably is worth adding a separate picotool bdev format command to unconditionally format the block device

README.md

lurch · 2025-09-01T09:54:22Z

main.cpp

@@ -94,6 +97,10 @@ static __forceinline int __builtin_ctz(unsigned x) {
 #ifndef BOOTROM_FAMILY_ID_MAX
 #define BOOTROM_FAMILY_ID_MAX       RP2350_ARM_NS_FAMILY_ID
 #endif
+#ifndef BLOCK_DEVICE_PARTITION_ID
+// The default 0x626C6F636B646576 value is the ASCII encoding of "blockdev"
+#define BLOCK_DEVICE_PARTITION_ID 0x626C6F636B646576


Should this ID also appear somewhere in a pico-sdk header, in case 3rd-party utilities also want to use it? Or do we expect any 3rd-party utilities to just copy'n'paste this into their own source code?

Yes, if it's decided that this is wanted as a way to identify block device partitions, then I'll open an SDK PR to add this to the SDK

main.cpp

will-v-pi force-pushed the block-device-support branch from ba574e8 to 73f4574 Compare February 5, 2025 16:20

kilograham added this to the 2.2.0 milestone Mar 22, 2025

will-v-pi added 12 commits August 18, 2025 17:50

Add bdev commands

2fe9c0a

Add ls, mkdir, put and get commands to access block devices Currently only supports littlefs

Only include bdev if has_libusb

c492cbc

Fix bazel build

a5d1f15

Merge put and get into cp, add rm, and make ls non-recursive with abi…

cd8ede0

…lity to specify directory

Add cat command, use partitions option, and format option

d99e21e

Respect write and format flags on block device

68f73ff

Default to writeable and formattable, but override based on bdev flags, or partition NSBOOT permissions

Add initial FatFS support

d560d39

Adds ls and cp commands for FatFS

Fix Bazel build

636aedb

Add filesystem auto-detection

09eb8a3

Add FatFS support to all bdev commands

4546450

Fix support for CircuitPython block device (Fat) and add full Flash T…

08d4d0d

…ranslation Layer (prevents doing lots of erases) Change Fat sector size back to 512, and consequently add in flash translation error - wasn't needed before with 4096 sector size Also enable LFN support

Fix segfault in release builds, and add output to all commands

c49b5d1

will-v-pi force-pushed the block-device-support branch from 73f4574 to c49b5d1 Compare August 19, 2025 12:55

Add commands to readme

efc5beb

will-v-pi marked this pull request as ready for review August 19, 2025 13:18

Add support for using partition with ID "blockdev"

e8c039b

Need to put BLOCK_DEVICE_PARTITION_ID into the SDK somewhere